Bulk Attach Subscriber Offer

This API is used to attach a new plan to multiple subscribers in a single call. The API currently supports attaching of individual offers (Regular plans) and Pool plans.

HTTP URL
POST	/api/v2/bulk/subscriber/offer

Eligibility

The Requester is eligible to attach a Regular plan to its sub-customers’ subscribers. The Requester is not allowed to attach a plan to its own subscribers unless the requester’s parent customer has:

Granted permission by turning on the allowOfferDelegation parameter.

Granted permission by turning on the allowOfferDelegation parameter
Assigned at least one plan to the requester

Pool plans can be attached to the specified subscriber (in URL) only if it was created for the requester’s sub account, and the specified subscriber belongs to this sub account.

API Request

Request Structure

Parameter	Type	M/O/CM	Description
bulk	Object	M	Array of main request body object.

Bulk data objects

Element	Type	M/O/CM	Description
subscriberIdentifiers	Object	M	Subscriber unique keys object, defines the search criteria
content	Object	M	Main elements container object

subscriberidentifiers data objects

Element	Type	M/O/CM	Description
type	String	M	Define the search criteria. ENUMs: IMSI, ICCID, MSISDN, IMEI
value	String	M	Type value. IMSI or ICCID or MSISDN or IMEI number.

Element

Type

M/O/CM

Description

type

String

Define the search criteria.

ENUMs: IMSI, ICCID, MSISDN, IMEI

value

String

Type value. IMSI or ICCID or MSISDN or IMEI number.

Content data objects

Parameter	Type	M/O/CM	Description
productOfferingId	UUID	M	Product catalog offer ID
priority	Numeric	O	Plan order of priority; the higher the numeric value, the higher priority the plan receives. For example, a plan with priority 100 precedes plan with priority 50. The Rater does not enforce the sequential order of any plan’s priorities and so it has no meaning. Note: The Rater does not enforce the uniqueness of an assigned priority between a subscriber’s plans. Therefore, prevent sending an existing plan’s priority value to this plan.
myOffer	Boolean	O	Determines whether to: Attach one of my Customer plans (Sell Plan offers) to my sub accounts’ subscribers OR Attach one of the Parent’s Buy Plans to my accounts’ subscribers. [myOffer] True = Request to attach a Parent plan (Buy Plan offer) to my own subscribers. This self-service functionality is allowed only when the sub-customer was defined by my Parent as authorized for delegation of Parent Plans [allow_offer_delegation = true]. [myOffer] False = Request to attach one of my Customer plans (Sell Plan offers) to my sub accounts subscribers (Normal operation) Default (if not provided) = False

Parameter

Type

M/O/CM

Description

productOfferingId

UUID

Product catalog offer ID

priority

Numeric

Plan order of priority; the higher the numeric value, the higher priority the plan receives.

For example, a plan with priority 100 precedes plan with priority 50.

The Rater does not enforce the sequential order of any plan’s priorities and so it has no meaning.

Note: The Rater does not enforce the uniqueness of an assigned priority between a subscriber’s plans. Therefore, prevent sending an existing plan’s priority value to this plan.

myOffer

Boolean

Determines whether to:

Attach one of my Customer plans (Sell Plan offers) to my sub accounts’ subscribers

Attach one of the Parent’s Buy Plans to my accounts’ subscribers.

[myOffer] True = Request to attach a Parent plan (Buy Plan offer) to my own subscribers. This self-service functionality is allowed only when the sub-customer was defined by my Parent as authorized for delegation of Parent Plans [allow_offer_delegation = true].

[myOffer] False = Request to attach one of my Customer plans (Sell Plan offers) to my sub accounts subscribers (Normal operation)

Default (if not provided) = False

API Response

Response Structure

Parameter	Type	M/O/CM	Description
bulk	Object	M	Array of main response body object.
pageable	Object	O	Paging information object displayed when an API call was successful. For a failure, it will be empty.

Bulk data objects

Parameter	Type	M/O/CM	Description
errorCode	String	O	Failure code.
errorMessage	String	O	Failure message.
requestId	UUID	CM	Request instance ID. To be used by external systems to query the call (operation) status: In progress Successful Failed. Displayed when an API call was successful. For a failure, it will be empty.
subscriberOfferId	UUID	M	Offer instance attached to the subscriber
subscriberIdentifiers	Object	M	Subscriber unique keys object, defines the search criteria
content	Object	O	Main response body object that reflects a single node of the original request.

subscriberidentifiers data objects

Parameter	Type	M/O/CM	Description
type	String	M	Define the search criteria. ENUMs: IMSI, ICCID, MSISDN, IMEI
value	String	M	Type value. IMSI or ICCID or MSISDN or IMEI number.

Parameter

Type

M/O/CM

Description

type

String

Define the search criteria.

ENUMs: IMSI, ICCID, MSISDN, IMEI

value

String

Type value. IMSI or ICCID or MSISDN or IMEI number.

Content data objects

Element	Type	M/O/CM	Description
productOfferingId	UUID	M	Product catalog offer ID
priority	Numeric	O	Plan order of priority; the higher the numeric value, the higher priority the plan receives.
myOffer	Boolean	M	Determines whether to: Attach one of my Customer plans (Sell Plan offers) to my sub accounts’ subscribers OR Attach one of the Parent’s Buy Plans to my accounts’ subscribers. [myOffer] True = Request to attach a Parent plan (Buy Plan offer) to my own subscribers. [myOffer] False = Request to attach one of my Customer plans (Sell Plan offers) to my sub accounts subscribers (Normal operation) Default if not provided is ‘false’

Element

Type

M/O/CM

Description

productOfferingId

UUID

Product catalog offer ID

priority

Numeric

Plan order of priority; the higher the numeric value, the higher priority the plan receives.

myOffer

Boolean

Determines whether to:

Attach one of my Customer plans (Sell Plan offers) to my sub accounts’ subscribers

Attach one of the Parent’s Buy Plans to my accounts’ subscribers.

[myOffer] True = Request to attach a Parent plan (Buy Plan offer) to my own subscribers.

[myOffer] False = Request to attach one of my Customer plans (Sell Plan offers) to my sub accounts subscribers (Normal operation)

Default if not provided is ‘false’

Pageable data objects

Element	Type	M/O/CM	Description
page	Numeric	M	Page number
size	Numeric	M	Page size. Number of requested elements per page
totalPages	Numeric	M	Total amount of available pages per requested page size
totalElements	Numeric	M	Total amount of retrieved elements

Error Codes

In addition to the general success and failure codes, the following error codes are possible.

Code	Message
GLOBAL_1001	Service unavailable. Please try again
SUBSCRIBER_1010	Failed to attach offer
AUTH_1012	You are not allowed to attach parent customer plans to your own SIM cards

Examples

Request Body

Copy

{
  "bulk": [
    {
      "subscriberIdentifiers": {
        "type": "IMSI",
        "value": "222013090961859"
      },
      "content": {
        "productOfferingId": "4543dedb-cce7-4bee-89f3-7af1447927e6",
        "priority": 10
      }
    },
    {
      "subscriberIdentifiers": {
        "type": "ICCID",
        "value": "8935711001000034535"
      },
      "content": {
        "productOfferingId": "e7fcef24-5c03-41dd-9e33-995b7d6f47e2",
        "priority": 10,
        "myOffer": true
      }
    }
  ]
}

Response Body: Full Success ACK

Copy

{
  "bulk": [
    {
      "errorCode": "",
      "errorMessage": "",
      "requestId": "ff74dca6-8e7f-4b85-a42b-13860913b370",
      "subscriberOfferId": "ab74dfe6-8e7f-4b45-a42b-14460913b459",
      "subscriberIdentifiers": {
        "type": "IMSI",
        "value": "222013090961963"
      },
      "content": {
        "productOfferingId": "4543dedb-cce7-4bee-89f3-7af1447927e6",
        "priority": 10,
        "myOffer": false
      }
    },
    {
      "errorCode": "",
      "errorMessage": "",
      "requestId": "7e74dce6-8eef-4c86-a4bb-1a860913c271",
      "subscriberOfferId": "bb64dfd6-2e1f-4a25-b32b-13461943c425",
      "subscriberIdentifiers": {
        "type": "ICCID",
        "value": "8935711001000035687"
      },
      "content": {
        "productOfferingId": "e7fcef24-5c03-41dd-9e33-995b7d6f47e2",
        "priority": 10,
        "myOffer": true
      }
    }
  ],
  "pageable": {
    "page": 0,
    "size": 10,
    "totalPages": 1,
    "totalElements": 1
  }
}

Response Body: Includes Failure(s) (NAK)

Copy

{
  "bulk": [
    {
      "errorCode": "AUTH_1012",
      "errorMessage": "You are not allowed to attach parent customer plans to your own SIM cards",
      "requestId": "",
      "subscriberIdentifiers": {
        "type": "IMSI",
        "value": "222013090961963"
      },
      "content": {
        "productOfferingId": "4543dedb-cce7-4bee-89f3-7af1447927e6",
        "priority": 10,
        "myOffer": false
      }
    }
  ],
  "pageable": {
    "page": 0,
    "size": 10,
    "totalPages": 1,
    "totalElements": 1
  }
}